#####################################################################
# File:         Assessible.py
# Product:      KnowledgeEngine
#
# Copyright:    Copyright (c) 2001, Faulkner Ltd.
# Author:       Brian Oliver
#
# Description:  This file defines the Assessible class/interface,
#               a place holder mix-in that identifies Components
#               which support persistent assessment state. For example:
#               CheckBoxes, TextBoxes, Options
#
# See Also:     Component, AssessmentCache
#####################################################################

#####################################################################
## KnowledgeEngine Library Imports
# (none)

#####################################################################
## Zope Library Imports
# (none)
 
#####################################################################
## Python Library Imports
# (none)

#####################################################################
## Assessible Class Definition
class Assessible:
    """
        A class to define basic persistent assessment state
        management methods for Components.
    """

    #---------------------------------------------------------------#

    def __init__(self):
        "Constructor for the object"    
        
        pass
        
    #---------------------------------------------------------------#
        
    def hasDBState(self, model, assessmentIdentity, componentIdentity):
        """
            ABSTRACT: Return if stored state exists for the specified
            assessment identity (a long)

            RETURN TYPE: Boolean
        """

        return None
    
    #---------------------------------------------------------------#
        
    def getDBState(self, model, assessmentIdentity, componentIdentity):
        """
            PRIVATE ABSTRACT: Return the stored state of the
            component given the specified assessment identity.

            Typically called by Assessible.getState() to retrieve
            stored state.

            NOTE: Must return a Python Type
        """

        return None
        
    #---------------------------------------------------------------#
        
    def getState(self, model, assessmentIdentity, componentIdentity):
        """
            ABSTRACT: Return the state of the component given the
            specified assessment identity.

            SEMANTICS: If the state is not store, a default should
            be returned.

            Typically calls Assessible.getDBState() to retrieve
            stored state.
            
            NOTE: Must return a Python Type
        """

        return None
        
    #---------------------------------------------------------------#
        
    def setDBState(self, model, assessmentIdentity, componentIdentity, value):
        """
            PRIVATE ABSTRACT: Set/update the stored state of the
            component given the specified assessment identity and
            value.

            Typically called by Assessible.setState() to set/update
            the stored state.

            NOTE: The value must be a Python Type
        """

        pass
    
    #---------------------------------------------------------------#
        
    def setState(self, model, assessmentIdentity, componentIdentity, value):
        """
            ABSTRACT: Set/update the state of the component given the
            specified assessment identity and value.

            Typically calls by Assessible.setDBState() to set/update
            the stored state.

            NOTE: The provided value may be from a HTML form.  It is
            the responsibility of this method to convert/cast/coerce
            the provided value into a Python type for the setDBState
            method.
        """

        pass
    
    #---------------------------------------------------------------#
        
    def removeState(self, componentContext = None):
        """
            ABSTRACT: Remove the state of the component from all
            assessments given the provided component context.
            
            CALLED BY: onBeforeDeleteComponent
        """

        pass
        
    #---------------------------------------------------------------#

    def getTypedAssessmentValue(self, formValue):
        """
            Returns the correctly typed python value for the
            specified HTTP form value
            
            Called By: AssesssmentCache.setState
        """
        
        #by default we don't do any type casting
        return formValue
        
    #---------------------------------------------------------------#

#####################################################################
## Class Initialisation
# (none)
